
/******************************************************
* Copyright (c):   2008, Apache License
* Project:         CS 152 HW 1
* File:            String.h
* Purpose:         Provide java-like String object (struct) for C.
* Start date:      August 31st, 2008
* Programmer:      Michael Gower
*
******************************************************
*/


#ifndef STRING_H_
#define STRING_H_

#include <string.h>

/**
 * String, a java-like string in C.
 */
// TODO change length to stringLength and maxLength
typedef struct StringTag
{

	/**
	 * The c string.
	 */
	char* cString;

	/**
	 * The length.
	 */
	int length; // more like maxLength

	struct StringTag* (*concat)(struct StringTag*, struct StringTag*);

}String, *pString, **StringList;


/**
 * Creates a new string from input.
 *
 * @param input The c string to copy as initial contents.
 * @returns a new pString with input copied as initial contents.
 */
pString String_new(const char* input);

/**
 * Returns the first index of any character in delims found in input.
 *
 * @param input The string to search.
 * @param delims A list of delimiters to search for.
 * @returns The index found, or -1 if not found.
 */
int String_indexOf(const pString input, const char* delims);

/**
 * Creates a clone of input.
 *
 * @param input The string to clone.
 * @returns a cloned string.
 */
pString String_clone(const pString input);

/**
 * Works like the head unix command.
 * Positive n will return the first n lines.
 * Negative n will return everything BUT the last n lines.
 * Returns with a trailing blank line.
 *
 * @param input The string to copy lines from.
 * @param n Copy the first n lines or all but the last -n lines.
 * @returns All copied lines.
 */
pString String_head(const pString input, int n);

/**
 * Trims whitespace from the input string.
 *
 * @param The string to trim.
 * @returns a trimmed copy of input.
 */
pString String_trim(const pString input);

/**
 * Concatenates two Strings.
 *
 * @param first The string to be appended to.
 * @param second The string to append.
 * @returns A new string containing the strings first and second concatenated.
 */
pString String_concat(pString first, pString second);

/**
 * Determines if two Strings are equal.
 *
 * @param first The first String to compare.
 * @param second The second String to compare.
 * @returns 1 if equal, 0 otherwise.
 */
int String_equals(const pString first, const pString second);

/**
 * Returns the line count of a given String.
 *
 * @param input The input String.
 * @returns the line count.
 */
int String_lineCount(const pString input);

/**
 * Returns the first line from input, is the same as StringHead(input, 1).
 * Expects either all /r/n's or /n's.  Returns line with same EOL at end.
 * No side effects, use with String_popLineGetStack.
 *
 * @param input The string to operate on.
 * @returns The first line from input.
 */
pString String_popLineGetLine(const pString input);

/**
 * Returns everything but the first line of input.
 * Same as the unix command tail -1.
 * Does not add EOL to end.
 *
 * @param input The String to work on.
 * @returns Everything but the first line of input.
 */
pString String_popLineGetStack(const pString input);

/**
 * Appends lineToAppend onto base.
 * base and lineToAppend must have same EOLs.
 *
 * @param base The string to be appended to.
 * @param lineToAppend The string to append.
 * @returns base concatenated to lineToAppend.
 */
pString String_appendLine(const pString base, const pString lineToAppend);

/**
 * Will resize to AT LEAST size.
 *
 * @param input The String to resize.
 * @param size The new size.
 * @returns A new String of size size and contents the same as input.
 */
pString String_resize(const pString input, int size);

/**
 * Copies starting and including start up to but not including end.
 *
 * @param input The String to copy from.
 * @param start the starting index, is copied.
 * @param end the ending index, is copied up to here, but not this index. 0 until end.
 */
pString String_substring(pString input, int start, int end);


#endif /* STRING_H_ */
